<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Template Inheritance</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="Smarty 3 Manual">
<link rel="up" href="advanced.features.html" title="Chapter 17. Advanced Features">
<link rel="prev" href="advanced.features.template.settings.html" title="Changing settings by template">
<link rel="next" href="advanced.features.streams.html" title="Streams">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Template Inheritance</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="advanced.features.template.settings.html">Prev</a> </td>
<th width="60%" align="center">Chapter 17. Advanced Features</th>
<td width="20%" align="right"> <a accesskey="n" href="advanced.features.streams.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
<div class="sect1" title="Template Inheritance">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="advanced.features.template.inheritance"></a>Template Inheritance</h2></div></div></div>
<p>
  Inheritance brings the concept of Object Oriented Programming to templates, allowing you to define
  one (or more) base templates that can be extended by child templates. Extending means that the child
  template can override all or some of the parent named block areas.
 </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem"><p>
      The inheritance tree can be as deep as you want, meaning you can extend a file that extends another 
      one that extends another one and so on.
    </p></li>
<li class="listitem"><p>
      The child templates can not define any content besides what's inside <a class="link" href="language.function.block.html" title="{block}"><code class="varname">{block}</code></a>
      tags they override. Anything outside of <a class="link" href="language.function.block.html" title="{block}"><code class="varname">{block}</code></a> tags will be removed.
    </p></li>
<li class="listitem"><p>
      The content of <a class="link" href="language.function.block.html" title="{block}"><code class="varname">{block}</code></a> tags from child and parent templates can be merged by 
      the <code class="literal">append</code> or <code class="literal">prepend</code> <a class="link" href="language.function.block.html" title="{block}"><code class="varname">{block}</code></a>
      tag option flags and <code class="literal">{$smarty.block.parent}</code> or <code class="literal">{$smarty.block.child}</code> placeholders.
    </p></li>
<li class="listitem"><p>
      Template inheritance is a compile time process which creates a single compiled template file. Compared to corresponding 
      solutions based on subtemplates included with the <a class="link" href="language.function.include.html" title="{include}"><code class="varname">{include}</code></a>
      tag it does have much better performance when rendering.
    </p></li>
<li class="listitem"><p>
      The child template extends its parent defined with the <a class="link" href="language.function.extends.html" title="{extends}"><code class="varname">{extends}</code></a> tag, 
      which must be the first line in the child template. Instead of using the <a class="link" href="language.function.extends.html" title="{extends}"><code class="varname">{extends}</code></a>
      tags in the template files you can define the whole template inheritance tree in the PHP script when you are calling <a class="link" href="api.fetch.html" title="fetch()"><code class="varname">fetch()</code></a>
      or <a class="link" href="api.display.html" title="display()"><code class="varname">display()</code></a> with the <code class="literal">extends:</code> template resource type. The later provides even more flexibillity.
    </p></li>
</ul></div>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
    When <em class="parameter"><code>$compile_check</code></em> is enabled, all files in the inheritance tree are checked for modifications upon each invocation. You may want to disable <em class="parameter"><code>$compile_check</code></em> on production servers for this reason.
  </p>
</div>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
    If you have a subtemplate which is included with <a class="link" href="language.function.include.html" title="{include}"><code class="varname">{include}</code></a> and it contains 
    <a class="link" href="language.function.block.html" title="{block}"><code class="varname">{block}</code></a> areas it works only if the <a class="link" href="language.function.include.html" title="{include}"><code class="varname">{include}</code></a>
    itself is called from within a surrounding  <a class="link" href="language.function.block.html" title="{block}"><code class="varname">{block}</code></a>. In the final parent template you may need a dummy <a class="link" href="language.function.block.html" title="{block}"><code class="varname">{block}</code></a> for it.
  </p>
</div>
<div class="example">
<a name="id459144"></a><p class="title"><b>Example 17.6. Template inheritance example</b></p>
<div class="example-contents">
<p>layout.tpl (parent)</p>
<pre class="programlisting">

&lt;html&gt;
&lt;head&gt;
  &lt;title&gt;{block name=title}Default Page Title{/block}&lt;/title&gt;
  {block name=head}{/block}
&lt;/head&gt;
&lt;body&gt;
{block name=body}{/block}
&lt;/body&gt;
&lt;/html&gt;

  </pre>
<p>myproject.tpl (child)</p>
<pre class="programlisting">

{extends file='layout.tpl'}
{block name=head}
  &lt;link href="/css/mypage.css" rel="stylesheet" type="text/css"/&gt;
  &lt;script src="/js/mypage.js"&gt;&lt;/script&gt;
{/block}


  </pre>
<p>mypage.tpl (grandchild)</p>
<pre class="programlisting">

{extends file='myproject.tpl'}
{block name=title}My Page Title{/block}
{block name=head}
  &lt;link href="/css/mypage.css" rel="stylesheet" type="text/css"/&gt;
  &lt;script src="/js/mypage.js"&gt;&lt;/script&gt;
{/block}
{block name=body}My HTML Page Body goes here{/block}

  </pre>
<p>To render the above use</p>
<pre class="programlisting">

 $smarty-&gt;display('mypage.tpl');

</pre>
<p>The resulting output is</p>
<pre class="programlisting">

&lt;html&gt;
&lt;head&gt;
  &lt;title&gt;My Page Title&lt;/title&gt;
  &lt;link href="/css/mypage.css" rel="stylesheet" type="text/css"/&gt;
  &lt;script src="/js/mypage.js"&gt;&lt;/script&gt;
&lt;/head&gt;
&lt;body&gt;
My HTML Page Body goes here
&lt;/body&gt;
&lt;/html&gt;
</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="id459208"></a><p class="title"><b>Example 17.7. Template inheritance by template resource <code class="literal">extends:</code></b></p>
<div class="example-contents">
<p>
      Instead of using <a class="link" href="language.function.extends.html" title="{extends}"><code class="varname">{extends}</code></a> tags in the template
      files you can define the inheritance tree in your PHP script by using the 
      <a class="link" href="resources.extends.html" title="Extends Template Resources"><code class="literal">extends:</code> resource</a> type.
    </p>
<p>
      The code below will return same result as the example above.
    </p>
<pre class="programlisting">

&lt;?php
$smarty-&gt;display('extends:layout.tpl|myproject.tpl|mypage.tpl'); 
?&gt;

   </pre>
</div>
</div>
<br class="example-break"><p>
  See also
  <a class="link" href="language.function.block.html" title="{block}"><code class="varname">{block}</code></a>,
   <a class="link" href="language.function.extends.html" title="{extends}"><code class="varname">{extends}</code></a>
   and  <a class="link" href="resources.extends.html" title="Extends Template Resources"><code class="literal">extends:</code> resource</a>
 </p>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="advanced.features.template.settings.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="advanced.features.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="advanced.features.streams.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Changing settings by template </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> Streams</td>
</tr>
</table>
</div>
</body>
</html>
